Skip to content

ci: add a calendar-version release workflow - #173

Open
uniqueg wants to merge 13 commits into
devfrom
release-workflow
Open

uniqueg wants to merge 13 commits into
devfrom
release-workflow

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 2, 2026 •

Copy link
Copy Markdown
Member

Closes #167

Summary

Replaces deploy.yml (GHCR on every CI-green push to main) with tag-driven releases, aligned with the current release workflow of cloud-registry-ui.

  • release.yml: on v* tags (vYYYY.M.MICRO), with the jobs Prepare release, Push release image, Scan release image, Release image and Publish release:
    • prepare checks the tag (CalVer, not in a future month, annotated, signature verified by GitHub), that the commit is on main, the version in package.json, the curated notes docs/releases/<version>.md (shared action publish-release, check-only) and a successful CI run for the push of the commit to dev.
    • push builds and pushes elixircloud/landing-page by digest (SBOM, provenance), untagged; scan scans exactly that digest (shared action scan-image), without credentials.
    • release-image attests, signs (cosign keyless) and tags the digest with the version and, if it is the highest release on main, latest.
    • publish creates the GitHub release with the shared action publish-release: curated notes, then GitHub's generated notes under ## Commits, **Full Changelog** last. Calendar versions are never below 1.0.0, so no release is a pre-release.
    • push and release-image run in the release environment (approval each). DOCKERHUB_ORG is kept for forks and the dry run.
  • scan.yml: weekly scan of the latest release's image (job Scheduled scan).
  • ci.yml:
    • push is branches: [dev], as the release check looks for a successful CI run for a push of the commit to dev; main no longer needs CI.
    • Concurrency from dev (ci: cancel PR runs only for new commits #189: only a new PR commit cancels runs), with push runs in a group per branch and commit, so the release commit's run is never cancelled.
    • New step Check release notes in Lint: checks every docs/releases/*.md with the checker of the pinned publish-release, requires the notes of the version in package.json once it is a release version (0.1.0 has none), and fails when that checker, the publish-release pins of release.yml and the README's pre-tag block use different commits (Dependabot bumps only the uses: pins).
  • docker-compose.yaml: elixircloud/landing-page:latest.
  • README: Deployment rewritten; Releasing (versions, release-prep PR with notes, pre-tag check block in sync with prepare, jobs and approvals, repository settings); rollback; moving the host to Docker Hub; tag and image badges instead of the Deploy badge.

Differences from the model

  • Tags are CalVer vYYYY.M.MICRO; no pre-releases; no CITATION.cff.
  • build-args: GA_MEASUREMENT_ID is kept from deploy.yml, because the site reads it at build time.
  • Added, not in the model: prepare rejects tags for future months, and latest is decided without them. Versions are typed by hand here and production follows latest, so a stray v2062.11.0, which can't be removed, would otherwise stop latest moving. The workflow warns when a release doesn't move latest.
  • The CI notes check sits in Lint (the repo has no docs job) and exempts the pre-release version 0.1.0.

Bumping the version

package.json stays at 0.1.0 until the first release-prep PR, which sets the version (npm version <version> --no-git-tag-version) and adds docs/releases/<version>.md.

Verification

  • actionlint 1.7.12 (with shellcheck 0.11.0) on all workflows: clean.
  • zizmor --offline 1.32.0 on all workflows: no findings.
  • check-release-versions.sh (maintainer's work folder, elixir-on-cloud/landing-page-167/): same CalVer pattern in release.yml, scan.yml and README; accepted and rejected tags; sort -V and git version-sort order; future-month filter and check: all OK.
  • check-ci-release-notes.sh (same folder; the repo has no shell test suite): runs the Check release notes step in fixtures against the real checker: 0.1.0 without notes passes; a CalVer version without notes fails; valid notes pass; notes with ## Commits fail; a checker commit that doesn't match the pins, or a README with another commit, fails.
  • Locally after merging dev (fce06b5): npm run lint, prettier check, npm test (261 tests) pass.
  • CI on 1d073ea (after merging dev at fce06b5, incl. feat: set a cache policy #206, fix: make next-sitemap a dev dependency #208, feat: share multi-select filters across listings #219-feat: update home page texts and favicon #221): all checks passed, including CI passed, Lint (with the new notes check, no notes yet) and Scan build.
  • Review: adversarial and quality reviewers, two rounds; no high findings. Fixed: checker-pin drift (CI check), host-update warning before the first release (medium), README job names and approvals, stale Audit text, tag-exists and ls-remote failure checks in the pre-tag block, Dependabot note, wrapping.
  • Dry-run release-prep commit: npm version 2026.11.0 plus docs/releases/2026.11.0.md passes the CI notes check locally.

Not run:

  • Fork dry run: none yet. Required before the first tag, as no job of release.yml has run on Actions. Prepared as Fish commands for the maintainer (see open question 2).
  • Scan of the release image: CI's Scan build scans the same Dockerfile with the same flags, but a vulnerability published between that run and the release can still fail the release after its tag.
  • Docker behaviour: the Compose and Watchtower behaviour in the rollback and host-move steps comes from their docs, not from a run.

Repository settings: the maintainer reported the release environment and rulesets as ready; I didn't read them. Immutable releases and vars.GA_MEASUREMENT_ID are unverified.

Declined review findings

  • Decide latest from published releases only: I filtered out future months instead, because the tag-based decision is what stops concurrent releases moving latest back (as in the model).
  • Move the pre-tag checks into one script shared by prepare and the README: the model keeps them inline with "keep in sync" comments; the CI step now at least catches checker-pin drift. A shared script would be an org-wide change (all release workflows), not one for this repo alone.
  • Deduplicate the "version tag exists" block of push and release-image, and the image name in scan.yml: same structure as the model; kept for alignment.
  • Many merge commits on the branch: the PR is squash-merged (ruleset).
  • Dependabot PRs bumping publish-release fail Lint until CHECKER_SHA and the README URL are bumped by hand: intended (keeps CI, pre-tag block and prepare on one checker); documented in the README.

Decisions

Made by the maintainer:

  • Merge timing: this PR merges only when the first release is near, as merging ends publishing to GHCR at once.
  • release environment: only Push release image and Release image run in it, so each needs an approval; Prepare release runs before any approval, Scan release image stays apart from credentials, and Publish release needs only contents: write.
  • latest: moves with the highest release on main; the host's Watchtower follows that tag.
  • Old Docker Hub latest (2024-09-02, last pulled 2026-10-31): its consumer is unknown and doesn't matter; it is not kept. The first release's Release image overwrites it; no migration.
  • GHCR images: removed by hand once a Docker Hub release has proved good. Until then they are the only fallback.
  • CI job name: the job in ci.yml stays Scan build, so Scan release image stays unique.
  • Who can do what: Keshav is a repo admin and can trigger a release but not approve it, which is intended.
  • Fork dry run: to be prepared for the maintainer (Fish commands, DOCKERHUB_ORG on the fork).

Open questions

  1. Host move: which host, and which branch does its checkout follow? What the repo says about production today:
    • Image: deploy.yml builds the image on every CI-green push to main and pushes it to GHCR as ghcr.io/elixir-cloud-aai/landing-page:latest and :sha-<commit> (last run 2026-11-02, main at 40ec1f8).
    • Host: docker-compose.yaml on dev runs the site from ghcr.io/elixir-cloud-aai/landing-page:latest on port 80, next to Watchtower 1.7.1, which polls GHCR every 5 minutes and restarts the site when latest changes. TLS is "expected to be terminated by a reverse proxy in front of it". The README on dev sets the host up with git clone (no --branch, so it checks out the default branch, dev) and docker compose up -d.
    • Not in the repo: which machine or provider serves elixir-on.cloud, who runs it, and whether its compose file is the repo's. Vercel only builds previews (vercel.json turns off main).
    • After this PR: nothing is pushed to GHCR any more. Releases push docker.io/elixircloud/landing-page:<version> and move :latest. The host keeps serving the last GHCR image until someone on it runs the README's "Moving the host to Docker Hub" steps once, after the first release: check out main (the README now clones --branch main, so the compose file matches the released code), git pull, docker pull elixircloud/landing-page:latest, docker compose up -d. Watchtower then follows Docker Hub. It can't make this switch itself, as it doesn't change the compose file.
    • To decide: who runs the steps on the host (Valentin?), and when (right after the first release). Recommendation: the host checkout follows main, as in the README: main only moves to released commits, so the compose file on the host always matches a release.
  2. Fork dry run before the first tag: required, not done. Recommendation: run the prepared Fish runbook (elixir-on-cloud/landing-page-167/fork-dry-run.md in the maintainer's work folder) in uniqueg/landing-page with DOCKERHUB_ORG set to a personal Docker Hub namespace, on the test tag v2026.11.0 in the fork (fork tags don't use up upstream versions). It checks every job, the approvals, the curated notes, signature and attestation verification, and a re-run of Publish release.

🤖 Generated with Claude Code

Summary by Sourcery

Adopt a gated, tag-driven calendar-version release process that publishes signed Docker images to Docker Hub and deploys the highest release as latest.

New Features:

  • Add tag-driven calendar-version releases that build, scan, sign, attest, publish, and deploy Docker images through Docker Hub.
  • Add scheduled weekly vulnerability scanning for the latest published release image.

Enhancements:

  • Require release commits to have successful CI on dev and validate release tags, versions, signatures, notes, and main branch ancestry.
  • Change CI push validation to run on dev only and verify curated release notes against the pinned release tooling.
  • Update deployment configuration and documentation for Docker Hub releases, latest-image tracking, host migration, and versioned rollbacks.

CI:

  • Replace automatic deployment on every main push with gated, approval-based release workflow jobs.

Deployment:

  • Move production image consumption from GHCR to Docker Hub and document the migration process.

Documentation:

  • Rewrite deployment and release documentation for calendar versions, release preparation, approvals, rollback, and repository settings.

Chores:

  • Remove the obsolete deploy workflow and update image and status badges.

uniqueg and others added 4 commits November 2, 2026 23:54
Replace the Deploy workflow, which published to GHCR for every push to
main, with release and scan workflows modelled on cloud-registry-ui:
versions are vYYYY.M.MICRO and the image goes to Docker Hub as
elixircloud/landing-page. Production follows `latest`, which the release
workflow moves to the highest release.

CI now runs on pushes to dev only, as the release workflow needs a run
for the push of the release commit to dev, and runs for pushes are no
longer cancelled by later ones, which would have left a release commit
without a run.

Closes #167

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011FSoqMUX3EU35poH13xMgG
Reject tags for months in the future and leave them out when deciding
`latest`: tags can't be removed, and such a tag would keep every later
release from moving `latest`, which production follows. Warn when a
release doesn't move `latest`.

Document moving the host from GHCR to Docker Hub, which is only safe
after the first release, as `latest` on Docker Hub is an image from
2024 until then. Pull before pinning in rollbacks, as `docker compose
up` ignores a failed pull for a service that can be built.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011FSoqMUX3EU35poH13xMgG
Stop the tag commands if `sha` is empty, as pushing ":main" would delete
the branch. Pull before un-pinning, so that the host doesn't restart
from its old local `latest`. Use the guarded steps for GHCR rollbacks
too, and restore the compose file before moving the host. Pick MICRO
from the tags rather than the releases, as a failed release uses up its
version. Word the warning about `latest` for an empty result.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011FSoqMUX3EU35poH13xMgG
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011FSoqMUX3EU35poH13xMgG
@vercel

vercel Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
landing-page Ready Ready Preview Nov 20, 2026 8:53pm UTC

@sourcery-ai

sourcery-ai Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

Configuration

Replace deployment-on-main with a tag-triggered release pipeline that validates releases, builds and scans an image digest, then signs, tags, and publishes it; add scheduled vulnerability scanning and adjust CI triggers and release-note checks.

  • .github/workflows/ci.yml L1-10, L27-31, L90-129 (+2 small edits)
  • .github/workflows/release.yml L1-412
  • .github/workflows/scan.yml L1-77
  • .trivyignore.yaml L2-6
  • docker-compose.yaml L3-5, L10-17
  • .github/workflows/deploy.yml (deleted)

Documentation

Document the Docker Hub deployment transition, rollback and host-move procedures, and the end-to-end calendar-version release process.

  • README.md L156-169, L174-183, L193-381 (+5 small edits)

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

uniqueg and others added 2 commits November 3, 2026 01:52
Keep the removal of the Deploy workflow, and both sides' README badges
without the Deploy ones.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011FSoqMUX3EU35poH13xMgG
CI now scans the image in `Scan build`, so the release steps no longer
need a local scan before tagging. Say that CI runs for pushes to dev
only, make the header of ci.yml one description after the merge, and
record that the GHCR images are removed by hand.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011FSoqMUX3EU35poH13xMgG
@codecov

codecov Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 49.86%. Comparing base (fce06b5) to head (1d073ea).

Additional details and impacted files
@@           Coverage Diff           @@
##              dev     #173   +/-   ##
=======================================
  Coverage   49.86%   49.86%           
=======================================
  Files          44       44           
  Lines        1105     1105           
  Branches      292      292           
=======================================
  Hits          551      551           
  Misses        479      479           
  Partials       75       75           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

uniqueg and others added 7 commits November 20, 2026 18:43
# Conflicts:
#	.github/workflows/ci.yml
#	.github/workflows/deploy.yml
Follow cloud-registry-ui's current release workflow:

- Curated notes in docs/releases/<version>.md, checked in `prepare`
  (publish-release with check-only) and published by a new job
  `publish` ("Publish release") with the shared action, instead of
  generated notes to edit by hand.
- The image job is now `release-image` ("Release image") and needs only
  `contents: read`; jobs are named "Push release image" and "Scan
  release image", unique across the workflows.
- CI's Lint job checks the notes with the same checker, and requires
  the notes of the version in package.json once it is a release
  version.
- Pins of login-action, cosign-installer and scan-image as in the
  model and CI.

README: release-prep step with the notes, the pre-tag block checks the
notes and existing releases, and the publish step no longer edits the
notes after the release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dependabot bumps only the `uses:` pins of publish-release: the Lint
job now fails when its checker or the README's pre-tag block uses
another commit, so that CI, the pre-tag checks and `prepare` run the
same checker.

README: name the release jobs in order and which wait for approval,
fix the Audit bullet (nothing deploys from main any more), and list
the tools the pre-tag block needs. Rewrap two comments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Until the first release, `latest` on Docker Hub is the 2024 image: a
host that pulls this compose file and restarts would serve it. Warn in
docker-compose.yaml and the Deployment section, and tell operators to
check that the host is on `main`.

The pre-tag block now stops if the tag exists already, and the Checks
section says that Dependabot's pin bumps of publish-release need the
checker commit updated by hand.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A failing `git ls-remote` gave empty output, so the check for an
existing tag passed. Also drop a doubled job name in step 4 and rewrap
the Audit bullet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sourcery-ai

sourcery-ai Bot commented Nov 20, 2026

Copy link
Copy Markdown

Linked issues

Checked at commit 1d073ea

#167 ci: add a release workflow with calendar versions · 7 of 9 met · 1 to check by hand

# Requirement Status Notes
1 Use calendar versions vYYYY.M.MICRO, with an unpadded month and MICRO starting at 0 each month. ✅ Met The workflow validates this format, and the README explains how to choose the next version.
2 Run a release workflow on v* tags; check the tag, package.json version, and successful CI for the commit. ✅ Met prepare checks the tag and commit, version, and successful CI run for a push of the release commit to dev.
3 Provide the release jobs in the release environment. 🟡 Partly met Push release image and Release image use the release environment, but Prepare release, Scan release image, and Publish release do not.
4 Choose an image registry and make the deployment refer to it. ✅ Met The image is published to Docker Hub, and docker-compose.yaml and the README describe that image and the host move.
5 Add scheduled scans of the released image. ✅ Met scan.yml schedules a weekly scan of the latest published release's image.
6 Replace deploy.yml. ✅ Met deploy.yml is removed and replaced by the tag-driven release workflow.
7 Agree with the people running the site how a release reaches production. 👀 Check by hand (manual process) A maintainer must confirm with the site operators who will move the host to Docker Hub after the first release and when they will do it.
8 Publish GitHub release notes in the organization's format. ✅ Met The shared publish-release action checks and publishes the curated notes followed by GitHub's generated notes.
9 Describe the release steps in the README, including how to pick a version. ✅ Met The README documents version selection, release preparation, checks, approvals, host migration, and rollback.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 6 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path=".github/workflows/release.yml" line_range="307" />
<code_context>
+              --format '{{ json .Manifest }}' 2>&1)" || status=$?
+          current=""
+          if [[ "${status}" == 0 ]]; then
+              current="$(jq -r .digest <<< "${output}")"
+          elif ! grep -qiE 'not found|manifest unknown' <<< "${output}"; then
+              echo "::error::Cannot check whether ${IMAGE_NAME}:${VERSION} exists: ${output}"
</code_context>
<issue_to_address>
**Release image verification fails**

When an image tag is inspected successfully during release-image, `docker buildx imagetools inspect --format '{{ json .Manifest }}'` returns a manifest body without a top-level `digest`, so `jq -r .digest` yields `null`; the digest comparison fails after the version tag is pushed, retries reject that tag, and the GitHub release remains unpublished.

Read the digest from a field that actually contains it instead of querying `.digest` on the manifest body.

Also at `.github/workflows/release.yml:372-373`.
</issue_to_address>

### Comment 2
<location path=".github/workflows/release.yml" line_range="46" />
<code_context>
+# run of another tag; `latest` is decided at the end of each run, from freshly
+# fetched tags on `main`
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
</code_context>
<issue_to_address>
**Older release overwrites latest**

When an older release checks `main` before a newer release tag is visible, and the newer release tags its image before the older run writes `latest`, the per-tag concurrency group allows both runs to overlap, so the older run uses its stale highest-release check to write its digest to `latest` after the newer run; production then serves the older image.

Serialize all release-tag runs with a shared concurrency group so a newer release cannot tag `latest` before an older run finishes.

Also at `.github/workflows/release.yml:343-374`, `README.md:218`.
</issue_to_address>

### Comment 3
<location path="README.md" line_range="331-333" />
<code_context>
+
+   ```bash
+   # ${sha:?} stops if it is empty: pushing ":main" would delete the branch
+   git push origin "${sha:?}:main" &&  # fails unless it is a fast-forward
+       git tag -s "v${version:?}" "${sha}" -m "v${version}" &&
+       git push origin "v${version}"
+   ```
+
</code_context>
<issue_to_address>
**Main advances without a release**

When the `main` push succeeds but `git tag -s` or the tag push fails, the main push can succeed before signing or pushing the tag fails, leaving `main` at an untagged release commit. No release workflow starts, and the documented invariant that `main` contains released commits is left false until an operator recovers.

Create and verify the signed tag before publishing refs, then push `main` and the tag atomically or document an explicit recovery that restores the invariant.
</issue_to_address>

### Comment 4
<location path=".github/workflows/release.yml" line_range="348-352" />
<code_context>
+          cd repo
+          git fetch --quiet --filter=blob:none --tags "${REPOSITORY_URL}" \
+              "+refs/heads/main:refs/remotes/origin/main"
+          highest="$(git tag -l 'v*' --merged origin/main \
+              | grep -E '^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$' \
+              | awk -F '[v.]' -v now="$(date -u +%Y%m)" '$2 * 100 + $3 <= now' \
+              | sort -V | tail -n 1 || true)"
+          if [[ "${highest}" == "${TAG}" ]]; then
+              latest=true
+          else
</code_context>
<issue_to_address>
**Failed releases block latest**

When a higher-version tag is on `main` while its release is awaiting approval or has failed before tagging its image, `highest` includes the higher tag even though its release has not produced a usable image, so the lower successful run sets `latest=false` and leaves production on the previous image (the 2024 image if this is the first release).

Determine the highest release from successfully released images, or otherwise ensure a completed lower release can move `latest` until the higher image is ready.
</issue_to_address>

### Comment 5
<location path=".github/workflows/release.yml" line_range="397-399" />
<code_context>
+# for edits that leave the title unchanged (e.g. of the description, also by
+# bots) share a group of their own, so that they don't wait for the run for
+# the pull request's commit
 concurrency:
   group: >-
     ci-${{
</code_context>
<issue_to_address>
**Queued releases can miss publication**

When one `publish` job is running while two or more releases reach that job, a newer run entering this concurrency group cancels the previous pending `publish` job; that release’s image is already tagged, but its GitHub release is never created unless someone notices and retries it.

Use a queue mechanism that retains every release’s publish job, or automatically retry a publish job canceled while pending.
</issue_to_address>

### Comment 6
<location path=".github/workflows/release.yml" line_range="50-392" />
<code_context>
+  prepare:
</code_context>
<issue_to_address>
**Environment on all jobs**

The issue asks for the release jobs to be in the `release` environment. Only `Push release image` and `Release image` use it; `Prepare release`, `Scan release image`, and `Publish release` do not.
</issue_to_address>

Sourcery assessment

Needs a human reviewer. 6 findings to address first, and a release can publish an image and tag it latest, which Watchtower then deploys to the production site; a bad release can therefore affect visitors before it is noticed. Reverting the workflow does not undo a published image or an already completed deployment, so recovery requires manually rolling back the host and publishing a corrected release.

Blocking findings: .github/workflows/release.yml:307, .github/workflows/release.yml:46, README.md:333, .github/workflows/release.yml:352, .github/workflows/release.yml:399, and 1 more


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

--format '{{ json .Manifest }}' 2>&1)" || status=$?
current=""
if [[ "${status}" == 0 ]]; then
current="$(jq -r .digest <<< "${output}")"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 High · Release image verification fails

When an image tag is inspected successfully during release-image, docker buildx imagetools inspect --format '{{ json .Manifest }}' returns a manifest body without a top-level digest, so jq -r .digest yields null; the digest comparison fails after the version tag is pushed, retries reject that tag, and the GitHub release remains unpublished.

Read the digest from a field that actually contains it instead of querying .digest on the manifest body.

Also at .github/workflows/release.yml:372-373.

Prompt for AI agents
In `.github/workflows/release.yml` at line 307:

**Release image verification fails**

When an image tag is inspected successfully during release-image, `docker buildx imagetools inspect --format '{{ json .Manifest }}'` returns a manifest body without a top-level `digest`, so `jq -r .digest` yields `null`; the digest comparison fails after the version tag is pushed, retries reject that tag, and the GitHub release remains unpublished.

Read the digest from a field that actually contains it instead of querying `.digest` on the manifest body.

Also at `.github/workflows/release.yml:372-373`.

# run of another tag; `latest` is decided at the end of each run, from freshly
# fetched tags on `main`
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Older release overwrites latest

When an older release checks main before a newer release tag is visible, and the newer release tags its image before the older run writes latest, the per-tag concurrency group allows both runs to overlap, so the older run uses its stale highest-release check to write its digest to latest after the newer run; production then serves the older image.

Serialize all release-tag runs with a shared concurrency group so a newer release cannot tag latest before an older run finishes.

Also at .github/workflows/release.yml:343-374, README.md:218.

Prompt for AI agents
In `.github/workflows/release.yml` at line 46:

**Older release overwrites latest**

When an older release checks `main` before a newer release tag is visible, and the newer release tags its image before the older run writes `latest`, the per-tag concurrency group allows both runs to overlap, so the older run uses its stale highest-release check to write its digest to `latest` after the newer run; production then serves the older image.

Serialize all release-tag runs with a shared concurrency group so a newer release cannot tag `latest` before an older run finishes.

Also at `.github/workflows/release.yml:343-374`, `README.md:218`.

Comment thread README.md
Comment on lines +331 to +333
git push origin "${sha:?}:main" && # fails unless it is a fast-forward
git tag -s "v${version:?}" "${sha}" -m "v${version}" &&
git push origin "v${version}"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Main advances without a release

When the main push succeeds but git tag -s or the tag push fails, the main push can succeed before signing or pushing the tag fails, leaving main at an untagged release commit. No release workflow starts, and the documented invariant that main contains released commits is left false until an operator recovers.

Create and verify the signed tag before publishing refs, then push main and the tag atomically or document an explicit recovery that restores the invariant.

Prompt for AI agents
In `README.md` at lines 331-333:

**Main advances without a release**

When the `main` push succeeds but `git tag -s` or the tag push fails, the main push can succeed before signing or pushing the tag fails, leaving `main` at an untagged release commit. No release workflow starts, and the documented invariant that `main` contains released commits is left false until an operator recovers.

Create and verify the signed tag before publishing refs, then push `main` and the tag atomically or document an explicit recovery that restores the invariant.

Comment on lines +348 to +352
highest="$(git tag -l 'v*' --merged origin/main \
| grep -E '^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$' \
| awk -F '[v.]' -v now="$(date -u +%Y%m)" '$2 * 100 + $3 <= now' \
| sort -V | tail -n 1 || true)"
if [[ "${highest}" == "${TAG}" ]]; then

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Failed releases block latest

When a higher-version tag is on main while its release is awaiting approval or has failed before tagging its image, highest includes the higher tag even though its release has not produced a usable image, so the lower successful run sets latest=false and leaves production on the previous image (the 2024 image if this is the first release).

Determine the highest release from successfully released images, or otherwise ensure a completed lower release can move latest until the higher image is ready.

Prompt for AI agents
In `.github/workflows/release.yml` at lines 348-352:

**Failed releases block latest**

When a higher-version tag is on `main` while its release is awaiting approval or has failed before tagging its image, `highest` includes the higher tag even though its release has not produced a usable image, so the lower successful run sets `latest=false` and leaves production on the previous image (the 2024 image if this is the first release).

Determine the highest release from successfully released images, or otherwise ensure a completed lower release can move `latest` until the higher image is ready.

Comment on lines +397 to +399
concurrency:
group: ${{ github.workflow }}-publish-release
cancel-in-progress: false

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Queued releases can miss publication

When one publish job is running while two or more releases reach that job, a newer run entering this concurrency group cancels the previous pending publish job; that release’s image is already tagged, but its GitHub release is never created unless someone notices and retries it.

Use a queue mechanism that retains every release’s publish job, or automatically retry a publish job canceled while pending.

Prompt for AI agents
In `.github/workflows/release.yml` at lines 397-399:

**Queued releases can miss publication**

When one `publish` job is running while two or more releases reach that job, a newer run entering this concurrency group cancels the previous pending `publish` job; that release’s image is already tagged, but its GitHub release is never created unless someone notices and retries it.

Use a queue mechanism that retains every release’s publish job, or automatically retry a publish job canceled while pending.

Comment on lines +50 to +392
prepare:
name: Prepare release
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
actions: read # read the CI runs of the release commit
outputs:
version: ${{ steps.version.outputs.version }}
sha: ${{ steps.version.outputs.sha }}
steps:
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# Full history and all tags, to check that the release commit is on
# `main`
fetch-depth: 0
# "Releasing" in `README.md` runs the checks of this job that need no tag
# before tagging: keep them in sync. Guards against accidental releases,
# e.g., of unmerged commits; the `release` environment's protection rules
# (required reviewer) are what actually control publishing
- name: Check release tag and commit
id: version
env:
TAG: ${{ github.ref_name }}
GH_TOKEN: ${{ github.token }}
REPOSITORY: ${{ github.repository }}
run: |
# vYYYY.M.MICRO; month and MICRO without leading zeros
pattern='^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$'
if [[ ! "${TAG}" =~ ${pattern} ]]; then
echo "::error::Tag '${TAG}' is not a release version (vYYYY.M.MICRO, e.g., v2026.11.0)"
exit 1
fi
# A tag can't be removed, and a version in the future would stay the
# highest one, which keeps later releases from becoming `latest`
IFS=. read -r year month _ <<< "${TAG#v}"
if (( year * 100 + month > $(date -u +%Y%m) )); then
echo "::error::Tag '${TAG}' is for a month in the future"
exit 1
fi
# Annotated, with a signature that GitHub verified
if [[ "$(git cat-file -t "refs/tags/${TAG}")" != "tag" ]]; then
echo "::error::Tag '${TAG}' is not annotated (git tag -s)"
exit 1
fi
verified="$(gh api "repos/${REPOSITORY}/git/tags/$(git rev-parse "refs/tags/${TAG}")" \
--jq .verification.verified)"
if [[ "${verified}" != "true" ]]; then
echo "::error::Tag '${TAG}' has no signature verified by GitHub (git tag -s)"
exit 1
fi
if ! git merge-base --is-ancestor HEAD origin/main; then
echo "::error::Release commit is not on 'main' (move 'main' to it first: git push origin <sha>:main)"
exit 1
fi
{
echo "version=${TAG#v}"
echo "sha=$(git rev-parse HEAD)"
} >> "${GITHUB_OUTPUT}"
# The version of the release is set in the release commit, so that the
# sources and the tag agree
- name: Check version in package.json
env:
VERSION: ${{ steps.version.outputs.version }}
run: |
package="$(jq -r .version package.json)"
if [[ "${package}" != "${VERSION}" ]]; then
echo "::error::Version in package.json ('${package}') doesn't match the tag ('${VERSION}')"
exit 1
fi
# The GitHub release (`publish`) starts with the curated notes of the
# tagged commit, so they must exist and be in the organization's format
# before anything is published; also checks that the tag points to the
# release commit and that no published release of it exists. Keep the
# pin in sync with `publish` and with the checker in `ci.yml`
- name: Check release notes
uses: elixir-cloud-aai/.github/actions/publish-release@31f22fccc1f3c597ed7c1d1f75b2f85522155348 # v1.1.0
with:
notes: docs/releases/${{ steps.version.outputs.version }}.md
commit: ${{ steps.version.outputs.sha }}
check-only: 'true'
# The checks above don't run the tests: require a successful run of the
# CI workflow for a push of the release commit to `dev` (before `main`
# moved to it); runs for pull requests test merge commits, not the commit
# itself. Re-runs that succeeded count
- name: Check that CI passed for the release commit
env:
GH_TOKEN: ${{ github.token }}
REPOSITORY: ${{ github.repository }}
SHA: ${{ steps.version.outputs.sha }}
run: |
runs="$(gh api "repos/${REPOSITORY}/actions/workflows/ci.yml/runs?head_sha=${SHA}&branch=dev&event=push&status=success&per_page=1" \
--jq .total_count)"
if [[ ! "${runs}" =~ ^[0-9]+$ || "${runs}" -lt 1 ]]; then
echo "::error::No successful run of the CI workflow (ci.yml) for a push of ${SHA} to dev; once CI passed for it, re-run this workflow"
exit 1
fi

# Builds the image of the release commit once and pushes it by digest only
# (untagged, with SBOM and provenance attestations), for `scan` to scan and
# `release-image` to sign and tag. Digests of runs that fail (or fail the
# scan) are never signed or tagged, but stay on Docker Hub, untagged
# (pullable by digest only)
push:
name: Push release image
needs: prepare
runs-on: ubuntu-latest
timeout-minutes: 30
# Docker Hub secrets (required reviewer)
environment: release
permissions:
contents: read
outputs:
digest: ${{ steps.push.outputs.digest }}
steps:
# The commit checked by `prepare`
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
ref: ${{ needs.prepare.outputs.sha }}
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
# OCI labels with the version, commit and source; `tags` only sets the
# version label (the image is tagged by digest in `release-image`, after
# the scan)
- name: Generate image labels
id: meta
uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
with:
images: ${{ env.IMAGE_NAME }}
flavor: latest=false
tags: type=raw,value=${{ needs.prepare.outputs.version }}
- name: Log in to Docker Hub
uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0
with:
username: ${{ secrets.DOCKERHUB_LOGIN }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
# Released images don't change: if the version tag exists (e.g. when
# re-running all jobs of a release), stop before building
- name: Check that the version isn't released yet
env:
VERSION: ${{ needs.prepare.outputs.version }}
run: |
# The digest of the version tag, if it exists; errors other than "not
# found" stop the run, so that it never passes by mistake
status=0
output="$(docker buildx imagetools inspect "${IMAGE_NAME}:${VERSION}" \
--format '{{ json .Manifest }}' 2>&1)" || status=$?
current=""
if [[ "${status}" == 0 ]]; then
current="$(jq -r .digest <<< "${output}")"
elif ! grep -qiE 'not found|manifest unknown' <<< "${output}"; then
echo "::error::Cannot check whether ${IMAGE_NAME}:${VERSION} exists: ${output}"
exit 1
fi
if [[ -n "${current}" ]]; then
echo "::error::${IMAGE_NAME}:${VERSION} exists already (${current}); release a new version instead"
exit 1
fi
- name: Build and push image by digest
id: push
uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
with:
context: .
outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
sbom: true
provenance: mode=max
labels: ${{ steps.meta.outputs.labels }}
# Public value, not a secret: it is visible in the page source. It
# goes into the build because the pages are rendered at build time
build-args: GA_MEASUREMENT_ID=${{ vars.GA_MEASUREMENT_ID }}

# Scans exactly the pushed digest (`<image>@<digest>`; public, so pulling it
# needs no login) with Trivy (shared action of elixir-cloud-aai/.github,
# pinned to the commit of a release; fails on fixable critical and high
# vulnerabilities, except those accepted in `.trivyignore.yaml`). Kept apart
# from `push`, `release-image` and `publish`, so that Trivy never runs next
# to the Docker Hub credentials, the `contents: write` token and the signing
# identity
scan:
name: Scan release image
needs: [prepare, push]
runs-on: ubuntu-latest
timeout-minutes: 20
permissions:
contents: read
steps:
# For `.trivyignore.yaml`
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
ref: ${{ needs.prepare.outputs.sha }}
- name: Check image digest
env:
DIGEST: ${{ needs.push.outputs.digest }}
run: |
if [[ ! "${DIGEST}" =~ ^sha256:[0-9a-f]{64}$ ]]; then
echo "::error::Invalid image digest '${DIGEST}'"
exit 1
fi
- name: Scan image
uses: elixir-cloud-aai/.github/actions/scan-image@31f22fccc1f3c597ed7c1d1f75b2f85522155348 # v1.1.0
with:
image: ${{ env.IMAGE_NAME }}@${{ needs.push.outputs.digest }}
category: release
upload: 'false'

# Attests, signs and tags the scanned digest
release-image:
name: Release image
needs: [prepare, push, scan]
runs-on: ubuntu-latest
timeout-minutes: 30
environment: release
permissions:
contents: read
id-token: write # Sigstore signing certificates
attestations: write # GitHub artifact attestations
env:
VERSION: ${{ needs.prepare.outputs.version }}
DIGEST: ${{ needs.push.outputs.digest }}
steps:
# The commit checked by `prepare`
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
ref: ${{ needs.prepare.outputs.sha }}
- name: Check image digest
run: |
if [[ ! "${DIGEST}" =~ ^sha256:[0-9a-f]{64}$ ]]; then
echo "::error::Invalid image digest '${DIGEST}'"
exit 1
fi
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
- name: Log in to Docker Hub
uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0
with:
username: ${{ secrets.DOCKERHUB_LOGIN }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
# Released images don't change: a version tag of another digest stops the
# run before this digest is attested and signed (the same digest, e.g.
# when re-running failed jobs, is fine)
- name: Check the version tag
run: |
# The digest of the version tag, if it exists; errors other than "not
# found" stop the run, so that it never passes by mistake
status=0
output="$(docker buildx imagetools inspect "${IMAGE_NAME}:${VERSION}" \
--format '{{ json .Manifest }}' 2>&1)" || status=$?
current=""
if [[ "${status}" == 0 ]]; then
current="$(jq -r .digest <<< "${output}")"
elif ! grep -qiE 'not found|manifest unknown' <<< "${output}"; then
echo "::error::Cannot check whether ${IMAGE_NAME}:${VERSION} exists: ${output}"
exit 1
fi
if [[ -n "${current}" && "${current}" != "${DIGEST}" ]]; then
echo "::error::${IMAGE_NAME}:${VERSION} already points to ${current}; release a new version instead"
exit 1
fi
# Of the scanned digest
- name: Attest build provenance
uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
with:
subject-name: ${{ env.IMAGE_NAME }}
subject-digest: ${{ env.DIGEST }}
push-to-registry: true
# No artifact metadata storage record (needs another permission)
create-storage-record: false
- name: Install cosign
uses: sigstore/cosign-installer@756fe2d284c7292c4e9b62c8a28f1e5629c59532 # v4.1.3
# The signature covers the digest, and so every tag of it
- name: Sign image
run: cosign sign --yes "${IMAGE_NAME}@${DIGEST}"
# Decided last, from freshly fetched tags (the repository is public, so no
# credentials are needed), so that neither a re-run of an older release
# nor a concurrent release moves `latest` back: the highest release among
# the tags on `main`, so that stray tags are ignored, leaving out months
# in the future, which `prepare` rejects. `sort -V` orders calendar
# versions correctly (v2026.9.0 before v2026.11.0). Production follows
# `latest`, so a release that doesn't move it says so
- name: Check whether this is the highest release
id: latest
env:
TAG: ${{ github.ref_name }}
REPOSITORY_URL: ${{ github.server_url }}/${{ github.repository }}.git
run: |
latest=false
git init --quiet repo
cd repo
git fetch --quiet --filter=blob:none --tags "${REPOSITORY_URL}" \
"+refs/heads/main:refs/remotes/origin/main"
highest="$(git tag -l 'v*' --merged origin/main \
| grep -E '^v20[0-9]{2}\.([1-9]|1[0-2])\.(0|[1-9][0-9]*)$' \
| awk -F '[v.]' -v now="$(date -u +%Y%m)" '$2 * 100 + $3 <= now' \
| sort -V | tail -n 1 || true)"
if [[ "${highest}" == "${TAG}" ]]; then
latest=true
else
echo "::warning::Highest release on main is ${highest:-none}, not ${TAG}: 'latest' stays as it is, and production doesn't update; release a version above it"
fi
echo "latest=${latest}" >> "${GITHUB_OUTPUT}"
# Tags `YYYY.M.MICRO` (and `latest`, which production follows, see
# `docker-compose.yaml`) point to the checked, scanned and signed digest:
# a single source is copied as is
- name: Tag image
env:
LATEST: ${{ steps.latest.outputs.latest }}
run: |
tags=("${IMAGE_NAME}:${VERSION}")
if [[ "${LATEST}" == "true" ]]; then
tags+=("${IMAGE_NAME}:latest")
fi
for tag in "${tags[@]}"; do
docker buildx imagetools create --tag "${tag}" "${IMAGE_NAME}@${DIGEST}"
actual="$(docker buildx imagetools inspect "${tag}" \
--format '{{ json .Manifest }}' | jq -r .digest)"
if [[ "${actual}" != "${DIGEST}" ]]; then
echo "::error::${tag} points to ${actual}, expected ${DIGEST}"
exit 1
fi
done

# Creates the GitHub release of the tag once the image is released: the
# curated notes of the tagged commit (`docs/releases/<version>.md`), then
# GitHub's generated notes under `## Commits`, with the `**Full Changelog**`
# line last; the latest release by version (calendar versions are never
# pre-releases). No environment: it needs no secrets, only
# `contents: write`. The tag must still point to the release commit. Fails
# on a draft of the tag, and on a published release unless an earlier
# attempt of this job created it (then it passes without changes). One at a
# time, so that the latest release is decided in order; a cancelled pending
# run is re-run like a failed one. The latest GitHub release (the action, by
# version among published releases) and the image's `latest` tag
# (`release-image`, by version among the tags on `main`) are decided
# separately, by the same rule: the highest version
publish:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Environment on all jobs

The issue asks for the release jobs to be in the release environment. Only Push release image and Release image use it; Prepare release, Scan release image, and Publish release do not.

Prompt for AI agents
In `.github/workflows/release.yml` at lines 50-392:

**Environment on all jobs**

The issue asks for the release jobs to be in the `release` environment. Only `Push release image` and `Release image` use it; `Prepare release`, `Scan release image`, and `Publish release` do not.

From #167:

Provide the release jobs in the `release` environment.

@keshxvdayal keshxvdayal left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read through release.yml, scan.yml, the CI and compose changes and the new Deployment/Releasing sections... logic looks good to me 👍 Checked that main (40ec1f8) is an ancestor of dev, so the fast-forward in the README works for the first release, and that the Dockerfile takes GA_MEASUREMENT_ID. I didn't run the workflow itself or check the repo settings, so the fork dry run before the first tag is still the real test, as you wrote.

Two non-blocking follow-ups: the Vercel parts (README lines 185-187 and 246, and vercel.json) are outdated now that we drop Vercel. I can do that in a separate PR. And Watchtower in the compose file is archived, which Pubgrade would replace later.

This branch was successfully deployed

1 active deployment
Preview – landing-page — 1d073ea5 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ci: add a release workflow with calendar versions

2 participants